Home Projects Bulk Messaging System API Reference Electron IPC API Gmail & SMTP IPC Handlers

Gmail & SMTP IPC Handlers

Referenced Files

gmail-handler.js smtp-handler.js main.js preload.js GmailForm.jsx SMTPForm.jsx BulkMailer.jsx README.md package.json

Table of Contents#

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
Appendices

Introduction#

This document provides comprehensive documentation for the Gmail and SMTP IPC handlers in the Electron-based bulk messaging application. It covers:

Gmail OAuth2 authentication flow initiation, authorization URL generation, and callback handling
Gmail token retrieval and validation
Email composition, attachment handling, and batch processing via Gmail API
SMTP email sending with connection parameters, authentication methods, and queue-like batch processing
Parameter validation schemas, error handling patterns, and retry mechanisms
Examples of email template processing, HTML content rendering, and progress tracking
Security considerations for credential storage and transmission

The handlers are exposed via Electron’s IPC mechanism and consumed by React components in the renderer process.

Project Structure#

The relevant parts of the project structure for this documentation are:

Electron main process handlers: gmail-handler.js, smtp-handler.js
Electron main process registration: main.js
Preload bridge exposing IPC APIs: preload.js
Frontend components using the handlers: GmailForm.jsx, SMTPForm.jsx, BulkMailer.jsx
Application documentation and configuration: README.md, electron/package.json

graph TB subgraph "Electron Main Process" MAIN["main.js"] GH["gmail-handler.js"] SH["smtp-handler.js"] end subgraph "Preload Bridge" PRELOAD["preload.js"] end subgraph "Renderer (React)" GMF["GmailForm.jsx"] SMF["SMTPForm.jsx"] BM["BulkMailer.jsx"] end GMF --> PRELOAD SMF --> PRELOAD BM --> PRELOAD PRELOAD --> MAIN MAIN --> GH MAIN --> SH

Diagram sources

Section sources

Core Components#

Gmail IPC handlers:
- gmail-auth: Initiates OAuth2 flow, opens authorization window, handles redirect callback, exchanges code for tokens, stores credentials
- gmail-token: Checks local token availability
- send-email: Sends emails via Gmail API with progress events and rate limiting
SMTP IPC handler:
- smtp-send: Validates SMTP config, creates transport, verifies connectivity, sends emails with progress events and rate limiting
Frontend integration:
- Preload exposes invokeable APIs for renderer
- GmailForm and SMTPForm orchestrate user actions and display progress
- BulkMailer coordinates form validation and handler invocation

Key runtime dependencies:

googleapis for Gmail API
nodemailer for SMTP
electron-store for secure local storage

Section sources

Architecture Overview#

The IPC architecture follows Electron’s model:

Renderer (React) invokes preload-exposed APIs
Preload forwards IPC invocations to main process handlers
Main process handlers perform external operations (OAuth, API calls, SMTP)
Handlers emit progress events back to renderer via IPC channels

sequenceDiagram participant UI as "GmailForm.jsx" participant PRE as "preload.js" participant M as "main.js" participant GH as "gmail-handler.js" participant GAPI as "Gmail API" participant STORE as "electron-store" UI->>PRE : invoke("gmail-auth") PRE->>M : ipcMain.handle("gmail-auth") M->>GH : handleGmailAuth() GH->>GH : create OAuth2 client GH->>GH : generateAuthUrl() GH->>UI : open BrowserWindow with authUrl UI-->>GH : user completes OAuth GH->>GH : getToken(code) GH->>STORE : store.set("gmail_token", token) GH-->>M : {success : true} M-->>PRE : result PRE-->>UI : result

Diagram sources

Detailed Component Analysis#

Gmail IPC Handlers#

Handler: gmail-auth#

Purpose: Initiate OAuth2 flow for Gmail
Steps:
- Validate environment variables for client ID and secret
- Create OAuth2 client with configured redirect URI
- Generate authorization URL with offline access and consent prompt
- Open BrowserWindow to display authorization page
- Listen for redirect to capture authorization code
- Exchange code for tokens and store credentials securely
- Resolve promise with success/failure result
Timeout: 5 minutes for OAuth completion
Error handling: Catches missing env vars, token exchange errors, and window closure

flowchart TD Start(["Invoke gmail-auth"]) --> CheckEnv["Check GOOGLE_CLIENT_ID/SECRET"] CheckEnv --> EnvOK{"Env vars present?"} EnvOK --> |No| ReturnErr["Return error"] EnvOK --> |Yes| CreateClient["Create OAuth2 client"] CreateClient --> GenAuthUrl["Generate auth URL"] GenAuthUrl --> OpenWin["Open BrowserWindow"] OpenWin --> WaitRedirect["Listen for redirect"] WaitRedirect --> GotCode{"Received code?"} GotCode --> |No| CloseWin["Close window
Resolve timeout"] GotCode --> |Yes| TokenExchange["getToken(code)"] TokenExchange --> StoreCreds["store.set('gmail_token')"] StoreCreds --> ResolveSuccess["Resolve success"]

Diagram sources

gmail-handler.js

Section sources

Handler: gmail-token#

Purpose: Check if a stored token exists
Behavior: Reads token from electron-store and returns presence flag
Use case: UI enables/disables Gmail actions based on token presence

Section sources

Handler: send-email#

Purpose: Send bulk emails via Gmail API
Input schema:
- recipients: array of email addresses
- subject: string
- message: HTML string
- delay: number (optional, milliseconds)
Processing:
- Validates token presence
- Sets up OAuth2 client with stored token
- Iterates recipients, emits progress events
- Constructs MIME message with HTML content-type
- Sends via gmail.users.messages.send
- Applies rate limiting delay between emails
Output schema:
- success: boolean
- results: array of { recipient, status, error? }

sequenceDiagram participant UI as "GmailForm.jsx" participant PRE as "preload.js" participant M as "main.js" participant GH as "gmail-handler.js" participant GAPI as "Gmail API" UI->>PRE : invoke("send-email", payload) PRE->>M : ipcMain.handle("send-email") M->>GH : handleSendEmail(event, payload) GH->>GH : validate token GH->>GH : setCredentials(token) GH->>GAPI : users.messages.send(raw) GAPI-->>GH : response GH->>UI : event.sender.send("email-progress", {status : "sent"}) GH->>GH : delay if not last GH-->>M : {success : true, results} M-->>PRE : result PRE-->>UI : result

Diagram sources

Section sources

SMTP IPC Handler#

Handler: smtp-send#

Purpose: Send bulk emails via SMTP
Input schema:
- smtpConfig: { host, port, secure, user, pass }
- recipients: array of email addresses
- subject: string
- message: HTML string
- delay: number (optional)
- saveCredentials: boolean (optional)
Processing:
- Validates smtpConfig fields
- Optionally saves sanitized config to electron-store
- Creates nodemailer transport with TLS settings
- Verifies connection via transporter.verify()
- Iterates recipients, emits progress events
- Builds mailOptions with HTML and plain text
- Sends via transporter.sendMail()
- Applies rate limiting delay between emails
Output schema:
- success: boolean
- results: array of { recipient, status, error? }

flowchart TD Start(["Invoke smtp-send"]) --> ValidateCfg["Validate smtpConfig fields"] ValidateCfg --> CfgOK{"Valid?"} CfgOK --> |No| ReturnErr["Return error"] CfgOK --> |Yes| SaveCfg["Optionally save config"] SaveCfg --> CreateTransport["Create nodemailer transport"] CreateTransport --> Verify["transporter.verify()"] Verify --> LoopRecips["For each recipient"] LoopRecips --> BuildMail["Build mailOptions (HTML + text)"] BuildMail --> SendMail["transporter.sendMail()"] SendMail --> Progress["event.sender.send('email-progress')"] Progress --> Delay["Apply delay if not last"] Delay --> Next{"More recipients?"} Next --> |Yes| LoopRecips Next --> |No| ReturnOk["Return {success:true, results}"]

Diagram sources

Section sources

Frontend Integration and Progress Tracking#

Preload exposes:
- authenticateGmail, getGmailToken, sendEmail
- sendSMTPEmail
- onProgress for email-progress events
GmailForm and SMTPForm:
- Validate forms and recipients
- Trigger handler invocations
- Render activity log with status and errors
Progress events:
- Current/total counters
- Per-recipient status (sending/sent/failed)
- Error details for failures

Section sources

Dependency Analysis#

External libraries and their roles:

googleapis: Gmail API client for OAuth2 and sending messages
nodemailer: SMTP transport creation and email sending
electron-store: Secure local storage for tokens/configs
dotenv: Environment variable loading for OAuth credentials

graph LR GH["gmail-handler.js"] --> GA["googleapis"] GH --> ES["electron-store"] SH["smtp-handler.js"] --> NM["nodemailer"] SH --> ES PRE["preload.js"] --> MAIN["main.js"] MAIN --> GH MAIN --> SH

Diagram sources

Section sources

Performance Considerations#

Rate limiting: Both handlers apply configurable delays between emails to avoid throttling and reduce spam risk.
Batch processing: Iterative loop with per-recipient progress updates ensures visibility and graceful failure handling.
Connection verification: SMTP handler verifies transport before sending to minimize failures mid-batch.
Memory footprint: Gmail handler constructs base64-encoded MIME messages; consider message size limits and HTML complexity.

[No sources needed since this section provides general guidance]

Troubleshooting Guide#

Common issues and resolutions:

Gmail OAuth timeout or window closed:
- Increase timeout window or re-initiate authentication
- Ensure redirect URI matches configured value
Missing environment variables:
- Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
Gmail API errors:
- Verify OAuth scopes and consent screen configuration
- Confirm token storage and refresh behavior
SMTP connection failures:
- Validate host/port/security settings
- Use correct authentication credentials
- Check firewall and TLS settings
Progress tracking not updating:
- Ensure onProgress listeners are attached in renderer
- Verify event channel names match

Section sources

Conclusion#

The Gmail and SMTP IPC handlers provide robust, secure, and user-friendly mechanisms for bulk email sending. They integrate seamlessly with Electron’s IPC model, offer comprehensive error handling and progress tracking, and adhere to security best practices for credential storage and transmission. The frontend components deliver a polished user experience with real-time feedback and validation.

[No sources needed since this section summarizes without analyzing specific files]

Appendices#

Parameter Validation Schemas#

Gmail send-email input:
- recipients: array
- subject: string
- message: string (HTML)
- delay?: number (default 1000 ms)
SMTP send-email input:
- smtpConfig: { host, port, secure, user, pass }
- recipients: array
- subject: string
- message: string (HTML)
- delay?: number (default 1000 ms)
- saveCredentials?: boolean

Section sources

Security Considerations#

OAuth2 credentials:
- Stored in environment variables; loaded via dotenv
- Tokens stored in electron-store; avoid logging sensitive data
SMTP credentials:
- Passwords are not saved to disk; only sanitized config is persisted
Transport security:
- TLS settings configured; self-signed certificate handling included
UI isolation:
- Context isolation enabled; preload bridge restricts exposed APIs

Section sources

Example Workflows#

Gmail OAuth2 flow:
- User clicks “Authenticate Gmail”
- App opens authorization window
- User grants consent and receives code
- App exchanges code for tokens and stores them
Bulk email sending (Gmail):
- User enters recipients, subject, and HTML message
- App invokes send-email with delay
- App displays per-recipient progress and final results
Bulk email sending (SMTP):
- User configures SMTP settings and imports recipients
- App validates config and verifies transport
- App sends emails with HTML and plain text variants

Section sources

Previous File Operations IPC

Next Whats App Event System

Bulk Messaging System

API Reference

Contact Management System

Desktop Application Architecture

Gmail API Integration

Python Backend Services

SMTP Email Integration

Security Implementation

Whats App Integration

Gmail & SMTP IPC Handlers

Table of Contents#

Introduction#

Project Structure#

Core Components#

Architecture Overview#

Detailed Component Analysis#

Gmail IPC Handlers#

Handler: gmail-auth#

Handler: gmail-token#

Handler: send-email#

SMTP IPC Handler#

Handler: smtp-send#

Frontend Integration and Progress Tracking#

Dependency Analysis#

Performance Considerations#

Troubleshooting Guide#

Conclusion#

Appendices#

Parameter Validation Schemas#

Security Considerations#

Example Workflows#